Подключение метода /api/v1/auth/error-directory на API-Шлюзе

Чтение HTTP-заголовков версии, проброс в gRPC Auth и сериализация справочника в JSON контракт.

Author

Services Task & Simulation Framework Documentation

Published

July 13, 2026

Краткая карточка задачи

Репозиторий / Компонент: backend-api (API Gateway / Шлюз).
Категория: Подключение метода к шлюзу.
Контракт взаимодействия: Внешний GET /api/v1/auth/error-directory -> Внутренний gRPC AuthService.GetErrorDirectory.
Спецификация gRPC контракта: См. Раздел: Protobuf Контракт: GetErrorDirectory
Статус: Готово к реализации

Ограничение публичной документации

В открытом доступе представлена демонстрационная версия задачи. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

Полная спецификация метода: Доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).
Для получения доступа: Обратитесь к системному аналитику или Product Owner вашей команды.

Предварительные условия (Prerequisites):
1. Убедиться, что клиентские gRPC-стабы (stubs) для сервиса AuthService успешно сгенерированы и обновлены в зависимостях репозитория шлюза на основе актуального Protobuf Контракта.
Инструкция по шагам:
1. На Шаге 1-2 (Обработка HTTP-запроса): Зарегистрировать внешний HTTP эндпоинт GET /api/v1/auth/error-directory. Извлечь обязательный Query-параметр app_lang и заголовок X-App-Version. Если заголовок версии отсутствует, возвращать клиенту статус HTTP 400 Bad Request.
2. На Шаге 3 (gRPC Вызов): Пересобрать извлеченные параметры в gRPC-структуру DirectoryRequest (где app_version = X-App-Version, language = app_lang) и направить запрос в микросервис auth-service. Обеспечить сквозное логирование поставляемого заголовка X-Request-ID.
3. Трансляция бизнес-ошибок: Если бэкенд возвращает статус-код INVALID_ARGUMENT (передан неподдерживаемый язык), прерывать выполнение и возвращать внешнему клиенту ответ HTTP 422 Unprocessable Entity (согласно Спецификации Ошибок Валидации).
4. Сериализация ответа согласно JSON Schema (Шаг 7): Полученный от gRPC бэкенда массив repeated ErrorItem сериализовать в валидный JSON-пакет. Выходной формат данных должен строго соответствовать следующей JSON Schema контракта ответа:

{
  "\$schema": "https://json-schema.org",
  "title": "ErrorDirectorySyncResponse",
  "type": "object",
  "required": ["status", "error_directory", "synced_at"],
  "properties": {
    "status": { "type": "string", "enum": ["success"] },
    "synced_at": { "type": "integer" },
    "error_directory": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "system_trigger",
          "grpc_status",
          "http_status",
          "canonical_code",
          "localized_text",
          "ui_reaction"
        ],
        "properties": {
          "system_trigger": { "type": "string" },
          "grpc_status": { "type": "string" },
          "http_status": { "type": "string" },
          "canonical_code": { "type": "string" },
          "localized_text": { "type": "string" },
          "ui_reaction": { "type": "string" }
        }
      }
    }
  }
}